from __future__ import annotations

import uuid
from datetime import datetime

from sqlalchemy.orm import validates

from ..extensions import db
from .associations import roles_users


# /**
#  * 作者: "test_LH"
#  * 日期: 2025-10-11
#  * 名称: User
#  * 作用: 定义系统用户实体，包含认证与权限信息
#  * 参数:
#  *   @param 无 类定义不接收参数
#  * 返回: 无
#  * 备注: 继承自 SQLAlchemy 模型基类
#  */
class User(db.Model):
    id = db.Column(db.Integer, primary_key=True)  # 用户主键，整型自增
    email = db.Column(db.String(255), unique=True, nullable=False)  # 用户邮箱，作为登录账号
    password = db.Column(db.String(255), nullable=False)  # 加密后的登录密码
    active = db.Column(db.Boolean(), default=True)  # 是否激活账户
    confirmed_at = db.Column(db.DateTime())  # 邮箱确认时间，用于安全校验
    fs_uniquifier = db.Column(  # Flask-Security 唯一标识
        db.String(64),
        unique=True,
        nullable=False,
        default=lambda: uuid.uuid4().hex,
    )
    created_at = db.Column(db.DateTime, default=datetime.utcnow)  # 创建时间戳

    roles = db.relationship(
        "Role",
        secondary=roles_users,
        backref=db.backref("users", lazy="dynamic"),
    )  # 用户关联的角色集合

    # /**
    #  * 作者: "test_LH"
    #  * 日期: 2025-10-11
    #  * 名称: __repr__
    #  * 作用: 返回用户实例的可读字符串表示，便于定位日志
    #  * 参数:
    #  *   @param self 当前 User 实例
    #  * 返回: 形如 <User email> 的字符串
    #  * 备注: 无
    #  */
    def __repr__(self) -> str:  # pragma: no cover - repr helper
        return f"<User {self.email}>"

    # /**
    #  * 作者: "test_LH"
    #  * 日期: 2025-10-11
    #  * 名称: validate_email
    #  * 作用: 确保传入的邮箱地址格式合法，缺少 @ 时阻止持久化
    #  * 参数:
    #  *   @param self 当前 User 实例
    #  *   @param key SQLAlchemy 传递的字段名称
    #  *   @param address 待验证的邮箱字符串
    #  * 返回: 经过验证的邮箱地址
    #  * 备注: 若格式不正确则抛出 ValueError
    #  */
    @validates("email")
    def validate_email(self, key: str, address: str) -> str:
        if "@" not in address:
            raise ValueError("Invalid email address")
        return address
